Creating and Drawing Picture Shapes (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 6 - Picture Shapes / Using Picture Shapes

Creating and Drawing Picture Shapes
QuickDraw GX provides a number of methods to create and draw pictures. In general, you can

define the items of the picture and draw them without creating a picture shape
define the items of the picture, incorporate them into a picture shape, and draw the picture shape

You can use the GXDrawPicture function to draw pictures using the first method. You send five parameters to this function: a count of how many shapes are in the picture, an array of references to the shapes you want drawn, and arrays of references to the overriding styles, inks, and transforms for those shapes. (See "Using Overriding Styles, Inks, and Transforms" beginning on page 6-38 for examples of overriding styles, inks, and transforms.) The GXDrawPicture function creates a temporary picture shape using the information in the arrays you provide, draws the picture shape, and then disposes of the temporary picture shape.
The GXDrawPicture function is convenient if you have a set of shapes (and overriding styles, inks, and transforms) that you want to draw only one time.
QuickDraw GX also provides a number of ways for you to create a more permanent picture shape--one that you can edit and draw repeatedly. To create a picture shape, you can

create an empty picture shape using the GXNewShape function and add items to the picture all at once using the GXSetPicture function
create an empty picture shape using the GXNewShape function and add items to the picture individually using the GXSetPictureParts function or the AddToPicture library function
create a picture with an initial set of items using the GXNewPicture function

In any of these three cases, you draw the picture shape using the GXDrawShape function.
The GXSetPicture function allows you to replace the entire geometry of a picture with a new set of items. For more information, see "Getting and Setting Picture Geometries" beginning on page 6-31.
The GXSetPictureParts function provides more sophisticated editing of a picture shape's item list. For more information, see "Adding Items to a Picture" beginning on page 6-32, and "Removing and Replacing Items in a Picture" beginning on page 6-35.
The GXNewPicture function is similar to the GXDrawPicture function in that it requires four arrays as parameters: arrays of references to the shapes, the overriding styles, the overriding inks, and the overriding transforms that make up the items of the picture shape. However, unlike the GXDrawPicture function, the GXNewPicture function creates a picture shape and returns a reference to it to your application. You can use this reference to draw the picture using the GXDrawShape function.
Listing 6-1 shows how to draw a picture of a house comprising three shapes: a rectangle for the house itself, another rectangle for the door, and a triangle for the roof. The sample function shown in this listing creates three shapes and draws them using the GXDrawPicture function.
Listing 6-1 Creating a simple picture of a house
static gxShape DrawHousePicture(void)
{
   const gxRectangle houseGeometry = {ff(90), ff(80),
                                      ff(200), ff(125)};
                                 
   const gxRectangle doorGeometry = {ff(155), ff(95),
                                     ff(170), ff(125)};
                                 
   const long roofGeometry[] = {1, /* number of contours */
                                3, /* number of points */
                                ff(80), ff(80),
                                ff(145), ff(50),
                                ff(210), ff(80)};
   gxShape houseRectangle;
   gxShape roofPolygon;
   gxShape doorRectangle;
   
   gxShape partsOfHouse[3];


   houseRectangle = GXNewRectangle(&houseGeometry);
   SetShapeCommonColor(houseRectangle, gxGray);
   roofPolygon = GXNewPolygons((gxPolygons *) roofGeometry);

   doorRectangle = GXNewRectangle(&doorGeometry);

   partsOfHouse[0] = houseRectangle;
   partsOfHouse[1] = roofPolygon;
   partsOfHouse[2] = doorRectangle;

   GXDrawPicture(3, partsOfHouse, nil, nil, nil);

   GXDisposeShape(houseRectangle);
   GXDisposeShape(roofPolygon);
   GXDisposeShape(doorRectangle);

};
The results of this sample function are shown in Figure 6-19.
Figure 6-19 A picture of a house with a roof and a door

The call to the GXDrawPicture function in this example creates a temporary picture shape, draws it, and then disposes of it. This function does not return a reference to the picture shape, and so your code never has access to this shape. To create a more permanent picture shape, one that your code can reference, you must first declare a shape reference variable:
gxShape housePicture;
Then you can replace the call to the GXDrawPicture function with calls to the GXNewPicture function and the GXDrawShape function:
housePicture = GXNewPicture(3, partsOfHouse, nil, nil, nil);
GXDrawShape(housePicture);
The resulting picture looks the same as the picture drawn by the GXDrawPicture function, which is shown in Figure 6-19, but in this case the picture shape exists until you explicitly dispose of it.
You can dispose of the picture shape using the GXDisposeShape function:
GXDisposeShape(housePicture);
In this example, disposing of the house picture also disposes of the three geometric shapes referenced by the house picture. That is, disposing of the house picture releases one of the references to each of the geometric shapes. However, before you dispose of the house picture, each of these shapes has an owner count of 2. (The owner count of each shape starts at 1 when you create it, and the call to the GXNewPicture function increments the owner count of each of the shapes.) Therefore, when you dispose of the house picture, the owner count of each of the geometric shapes decrements to 1. To free the memory used by these shapes, you must still dispose of them individually--just as you created them:
GXDisposeShape(houseRectangle);
GXDisposeShape(roofPolygon);
GXDisposeShape(doorRectangle);
Notice that you can dispose of these three geometric shapes before you dispose of the house picture, as shown in Listing 6-2.
Listing 6-2 Disposing of shapes contained in a picture before disposing of the picture
housePicture = GXNewPicture(3, partsOfHouse, nil, nil, nil);

GXDisposeShape(houseRectangle);
GXDisposeShape(roofPolygon);
GXDisposeShape(doorRectangle);

GXDrawPicture(housePicture);

GXDisposeShape(housePicture);
In this example, disposing of the three geometric shapes decrements their owner count by 1, but does not free their memory because the house picture shape still contains a reference to each of the three shapes. Only when the house picture is disposed of is the memory occupied by these three geometric shapes freed.
For information about the GXDrawPicture function, see page 6-67. For information about the GXNewPicture function, see page 6-57.